
/*
 * Copyright 2002-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2020原作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证
 *许可下的限制。
 */

package org.springframework.mail.javamail;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;

import jakarta.activation.FileTypeMap;
import jakarta.activation.MimetypesFileTypeMap;

import org.springframework.beans.factory.InitializingBean;
import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.Resource;
import org.springframework.lang.Nullable;

/**
 * Spring-configurable {@code FileTypeMap} implementation that will read
 * MIME type to file extension mappings from a standard JavaMail MIME type
 * mapping file, using a standard {@code MimetypesFileTypeMap} underneath.
 *
 * <p>The mapping file should be in the following format, as specified by the
 * Java Activation Framework:
 *
 * <pre class="code">
 * # map text/html to .htm and .html files
 * text/html  html htm HTML HTM</pre>
 *
 * Lines starting with {@code #} are treated as comments and are ignored. All
 * other lines are treated as mappings. Each mapping line should contain the MIME
 * type as the first entry and then each file extension to map to that MIME type
 * as subsequent entries. Each entry is separated by spaces or tabs.
 *
 * <p>By default, the mappings in the {@code mime.types} file located in the
 * same package as this class are used, which cover many common file extensions
 * (in contrast to the out-of-the-box mappings in {@code activation.jar}).
 * This can be overridden using the {@code mappingLocation} property.
 *
 * <p>Additional mappings can be added via the {@code mappings} bean property,
 * as lines that follow the {@code mime.types} file format.
 *
 * @author Rob Harrop
 * @author Juergen Hoeller
 * @since 1.2
 * @see #setMappingLocation
 * @see #setMappings
 * @see jakarta.activation.MimetypesFileTypeMap
 */
/**
 *Spring可配置的｛@code FileTypeMap｝实现将读取
 *从标准JavaMail MIME类型到文件扩展名的MIME类型映射
 *映射文件，使用下面的标准｛@code MimetypesFileTypeMap｝。
 *
 *<p>映射文件应采用以下格式，由
 *Java激活框架：
 *
 *<pre-class=“code”>
 *#将text/html映射到.htm和.html文件
 *text/html/html htm html htm</pre>
 *
 *以{@code#}开头的行将被视为注释并被忽略。全部的
 *其他行被视为映射。每个映射行都应包含MIME
 *键入作为第一个条目，然后将每个文件扩展名映射到该MIME类型
 *作为后续条目。每个条目都用空格或制表符分隔。
 *
 *＜p＞默认情况下，位于
 *使用了与此类相同的包，其中包含许多常见的文件扩展名
 *（与{@code-activation.jar}中开箱即用的映射相反）。
 *这可以使用｛@code mappingLocation｝属性重写。
 *
 *＜p＞可以通过{@code-mappings}bean属性添加其他映射，
 *作为遵循{@codemime.types}文件格式的行。
 *
 *@作者Rob Harrop
 *@作者Juergen Hoeller
 *@自1.2起
 *@参见#setMappingLocation
 *@参见#setMappings
 *@参见jakarta.activation.MimetypesFileTypeMap
 */
public class ConfigurableMimeFileTypeMap extends FileTypeMap implements InitializingBean {

	/**
	 * The {@code Resource} to load the mapping file from.
	 */
	/**
	 *要从中加载映射文件的｛@code Resource｝。
	 */
	private Resource mappingLocation = new ClassPathResource("mime.types", getClass());

	/**
	 * Used to configure additional mappings.
	 */
	/**
	 *用于配置其他映射。
	 */
	@Nullable
	private String[] mappings;

	/**
	 * The delegate FileTypeMap, compiled from the mappings in the mapping file
	 * and the entries in the {@code mappings} property.
	 */
	/**
	 *从映射文件中的映射编译的委托FileTypeMap
	 *以及{@code-mappings}属性中的条目。
	 */
	@Nullable
	private FileTypeMap fileTypeMap;


	/**
	 * Specify the {@code Resource} from which mappings are loaded.
	 * <p>Needs to follow the {@code mime.types} file format, as specified
	 * by the Java Activation Framework, containing lines such as:<br>
	 * {@code text/html  html htm HTML HTM}
	 */
	/**
	 *指定从中加载映射的｛@code Resource｝。
	 *<p>需要遵循指定的｛@code-mime.types｝文件格式
	 *通过Java激活框架，包含以下行：<br>
	 *｛@code-text/html/htmHTML htm｝
	 */
	public void setMappingLocation(Resource mappingLocation) {
		this.mappingLocation = mappingLocation;
	}

	/**
	 * Specify additional MIME type mappings as lines that follow the
	 * {@code mime.types} file format, as specified by the
	 * Java Activation Framework. For example:<br>
	 * {@code text/html  html htm HTML HTM}
	 */
	/**
	 *将其他MIME类型映射指定为
	 *｛@code mime.types｝文件格式，由
	 *Java激活框架。例如：<br>
	 *｛@code-text/html/htmHTML htm｝
	 */
	public void setMappings(String... mappings) {
		this.mappings = mappings;
	}


	/**
	 * Creates the final merged mapping set.
	 */
	/**
	 *创建最终合并的映射集。
	 */
	@Override
	public void afterPropertiesSet() {
		getFileTypeMap();
	}

	/**
	 * Return the delegate FileTypeMap, compiled from the mappings in the mapping file
	 * and the entries in the {@code mappings} property.
	 * @see #setMappingLocation
	 * @see #setMappings
	 * @see #createFileTypeMap
	 */
	/**
	 *返回从映射文件中的映射编译的委托FileTypeMap
	 *以及{@code-mappings}属性中的条目。
	 *@参见#setMappingLocation
	 *@参见#setMappings
	 *@参见#createFileTypeMap
	 */
	protected final FileTypeMap getFileTypeMap() {
		if (this.fileTypeMap == null) {
			try {
				this.fileTypeMap = createFileTypeMap(this.mappingLocation, this.mappings);
			}
			catch (IOException ex) {
				throw new IllegalStateException(
						"Could not load specified MIME type mapping file: " + this.mappingLocation, ex);
			}
		}
		return this.fileTypeMap;
	}

	/**
	 * Compile a {@link FileTypeMap} from the mappings in the given mapping file
	 * and the given mapping entries.
	 * <p>The default implementation creates an Activation Framework {@link MimetypesFileTypeMap},
	 * passing in an InputStream from the mapping resource (if any) and registering
	 * the mapping lines programmatically.
	 * @param mappingLocation a {@code mime.types} mapping resource (can be {@code null})
	 * @param mappings an array of MIME type mapping lines (can be {@code null})
	 * @return the compiled FileTypeMap
	 * @throws IOException if resource access failed
	 * @see jakarta.activation.MimetypesFileTypeMap#MimetypesFileTypeMap(java.io.InputStream)
	 * @see jakarta.activation.MimetypesFileTypeMap#addMimeTypes(String)
	 */
	/**
	 *根据给定映射文件中的映射编译｛@link FileTypeMap｝
	 *以及给定的映射条目。
	 *＜p＞默认实现创建激活框架｛@link MimetypesFileTypeMap｝，
	 *从映射资源（如果有）传入InputStream并注册
	 *以编程方式绘制映射线。
	 *@param mappingLocation一个｛@code mime.types｝映射资源（可以是｛@code-null｝）
	 *@param映射MIME类型映射行的数组（可以是｛@code null｝）
	 *@返回编译后的FileTypeMap
	 *如果资源访问失败，@throws IOException
	 *@参见jakarta.activation.MimetypesFileTypeMap#MimetypesFileTypeMap（java.io.InputStream）
	 *@seejakarta.activation.MimetypesFileTypeMap#addMimeTypes（字符串）
	 */
	protected FileTypeMap createFileTypeMap(@Nullable Resource mappingLocation, @Nullable String[] mappings) throws IOException {
		MimetypesFileTypeMap fileTypeMap = null;
		if (mappingLocation != null) {
			try (InputStream is = mappingLocation.getInputStream()) {
				fileTypeMap = new MimetypesFileTypeMap(is);
			}
		}
		else {
			fileTypeMap = new MimetypesFileTypeMap();
		}
		if (mappings != null) {
			for (String mapping : mappings) {
				fileTypeMap.addMimeTypes(mapping);
			}
		}
		return fileTypeMap;
	}


	/**
	 * Delegates to the underlying FileTypeMap.
	 * @see #getFileTypeMap()
	 */
	/**
	 *委托到基础FileTypeMap。
	 *@参见#getFileTypeMap（）
	 */
	@Override
	public String getContentType(File file) {
		return getFileTypeMap().getContentType(file);
	}

	/**
	 * Delegates to the underlying FileTypeMap.
	 * @see #getFileTypeMap()
	 */
	/**
	 *委托到基础FileTypeMap。
	 *@参见#getFileTypeMap（）
	 */
	@Override
	public String getContentType(String fileName) {
		return getFileTypeMap().getContentType(fileName);
	}

}
